Skip to content

feat(docs): document the batch status data type - #12263

Open
kozlek wants to merge 1 commit into
devs/kozlek/devs/kozlek/batch-status-data-type/switch-namespaced-documented-data-type-marker--1575ebfdfrom
devs/kozlek/devs/kozlek/batch-status-data-type/document-batch-status-data-type--c5cd0801
Open

feat(docs): document the batch status data type#12263
kozlek wants to merge 1 commit into
devs/kozlek/devs/kozlek/batch-status-data-type/switch-namespaced-documented-data-type-marker--1575ebfdfrom
devs/kozlek/devs/kozlek/batch-status-data-type/document-batch-status-data-type--c5cd0801

Conversation

@kozlek

@kozlek kozlek commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

A batch's status.code appeared on the API reference as a bare list of
values with no explanation, and nowhere else in the docs. Readers seeing
a status in an API response, in the CLI, or on a dashboard chip had no
way to find out what it meant.

Add a Batch Status section to the data-types page, rendering a table
generated from the OpenAPI spec so the codes and their descriptions come
from the engine rather than being hand-maintained, and cross-reference it
from the monitoring and batches pages. The table goes through the shared
reader added earlier, so it already handles the shapes a synced schema
can arrive in — a $ref to a hoisted component in particular, which the
engine's enum deduplication produces.

Extend the anchor build gate to scan the API spec alongside the
configuration schema. This is the first data type marked in the API
spec, and schema syncs land as direct pushes to main, so the deploy
build is the only gate they pass through.

The bundled schemas are what the sync bot will deliver once the engine
side merges. They carry the per-value documentation as x-mergify-enum,
a positional array aligned with enum holding a description, an optional
display title and a deprecation flag, and the data-type marker under its
namespaced spelling. x-enum-descriptions is gone: that name is an
established openapi-generator convention for a positional array of
strings, and publishing a map under it would mislead the SDK generators
customers run against our spec.

Part of MRGFY-8330

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com

Depends-On: #12319

Copilot AI review requested due to automatic review settings July 29, 2026 16:44
@mergify
mergify Bot had a problem deploying to Mergify Merge Protections July 29, 2026 16:44 Failure
@mergify

mergify Bot commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Merge Protections

🔴 3 of 7 protections blocking · waiting on 👀 reviews and ⛓️ dependency

Protection Waiting on
🔴 ⛓️ Depends-On Requirements ⛓️ dependency
🔴 👀 Review Requirements 👀 reviews
🔴 🔎 Reviews 👀 reviews
🟢 🤖 Continuous Integration
🟢 Enforce conventional commit
🟢 📕 PR description
🟢 🚦 Auto-queue

🔴 ⛓️ Depends-On Requirements

Waiting for

This rule is failing.

Requirement based on the presence of Depends-On in the body of the pull request

🔴 👀 Review Requirements

Waiting for

  • #approved-reviews-by >= 2
This rule is failing.
  • any of:
    • #approved-reviews-by >= 2
    • author = dependabot[bot]
    • all of:
      • author = mergify-ci-bot
      • -head ~= ^docs-agent/

🔴 🔎 Reviews

Waiting for

  • #review-requested = 0
This rule is failing.
  • #review-requested = 0
  • #changes-requested-reviews-by = 0
  • #review-threads-unresolved = 0

Show 4 satisfied protections

🟢 🤖 Continuous Integration

  • all of:
    • check-success = build
    • check-success = lint
    • check-success = test
    • any of:
      • check-success = test-broken-links
      • label = ignore-broken-links
    • any of:
      • check-success=Cloudflare Pages
      • -head-repo-full-name~=^Mergifyio/

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

  • title ~= ^(fix|feat|internal|docs|style|refactor|perf|test|build|ci|chore|revert|ui)(?:\(.+\))?!?:

🟢 📕 PR description

  • body ~= (?ms:.{48,})

🟢 🚦 Auto-queue

When all merge protections are satisfied, this pull request will be queued automatically.

@mergify
mergify Bot requested a review from a team July 29, 2026 16:47

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Documents the merge queue batch status.code data type and ensures the docs build/CI gate catches future schema-driven anchor drift by validating both the configuration schema and the OpenAPI schema.

Changes:

  • Adds a new Batch Status section to /configuration/data-types, rendering status codes/descriptions from the synced OpenAPI schema.
  • Cross-references the new data type from merge queue monitoring and batch resolution docs.
  • Extends the anchor validation gate (and its tests) to scan public/api-schemas.json in addition to the configuration schema.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
src/util/dataType.test.ts Adds API schema coverage to the data-type anchor test suite and pins the new batch-status anchor.
src/content/docs/merge-queue/monitoring.mdx Links readers to the Batch Status reference from the monitoring page.
src/content/docs/merge-queue/batches.mdx References batch status codes during batch failure resolution/splitting explanation.
src/content/docs/configuration/data-types.mdx Adds the Batch Status section and renders the new table component.
src/components/Tables/BatchStatusCodes.tsx New table component that reads status enums + descriptions from the OpenAPI schema.
public/api-schemas.json Updates BatchStatus schema metadata to include x-enum-descriptions and the x-has-data-type marker.
integrations/validate-data-type-anchors.ts Extends the build-time anchor validation to check both synced schemas.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread src/components/Tables/BatchStatusCodes.tsx Outdated
@kozlek
kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/document-batch-status-data-type--c5cd0801 branch from e2af176 to 5e644c7 Compare July 30, 2026 13:20
@kozlek

kozlek commented Jul 30, 2026

Copy link
Copy Markdown
Contributor Author

Revision history

# Type Changes Reason Date
1 initial e2af176 2026-07-30 13:20 UTC
2 content e2af176 → 5e644c7 2026-07-30 13:20 UTC
3 content 5e644c7 → dc555d0 2026-08-03 19:22 UTC
4 content dc555d0 → fad7e3e 2026-08-04 07:58 UTC
5 content fad7e3e → c73d075 2026-08-04 17:09 UTC
6 rebase c73d075 → 4c75840 (rebase only) 2026-08-05 13:05 UTC
7 content 4c75840 → f86e05f (raw) 2026-08-05 13:52 UTC
8 rebase f86e05f → 62175a1 (rebase only) 2026-08-05 14:00 UTC

@mergify
mergify Bot had a problem deploying to Mergify Merge Protections July 30, 2026 13:20 Failure
jd
jd previously approved these changes Jul 31, 2026
@mergify
mergify Bot requested a review from a team July 31, 2026 08:57
@kozlek

kozlek commented Aug 3, 2026

Copy link
Copy Markdown
Contributor Author

This pull request is part of a Mergify stack:

# Pull Request Link
1 fix(docs): show accepted values for API parameters typed by a shared enum #12299
2 refactor(docs): read documented enum values through one shared reader #12293
3 fix(docs): sanitize the HTML the schema-driven tables inject #12304
4 feat(docs): switch to the namespaced documented-data-type marker #12319
5 feat(docs): document the batch status data type #12263 👈

@kozlek
kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/document-batch-status-data-type--c5cd0801 branch from 5e644c7 to dc555d0 Compare August 3, 2026 19:22
@mergify
mergify Bot dismissed jd’s stale review August 3, 2026 19:22

Pull request has been modified.

@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 3, 2026 19:22 Failure
@kozlek
kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/document-batch-status-data-type--c5cd0801 branch from dc555d0 to fad7e3e Compare August 4, 2026 07:58
@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 4, 2026 07:58 Failure
@kozlek
kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/document-batch-status-data-type--c5cd0801 branch from fad7e3e to c73d075 Compare August 4, 2026 17:10
@kozlek
kozlek changed the base branch from main to devs/kozlek/devs/kozlek/batch-status-data-type/accept-namespaced-documented-data-type-marker--203218c9 August 4, 2026 17:10
@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 4, 2026 17:10 Failure
@kozlek
kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/accept-namespaced-documented-data-type-marker--203218c9 branch from 40c537b to 979f038 Compare August 5, 2026 13:05
@kozlek
kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/document-batch-status-data-type--c5cd0801 branch from c73d075 to 4c75840 Compare August 5, 2026 13:05
@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 5, 2026 13:05 Failure
@kozlek
kozlek marked this pull request as ready for review August 5, 2026 13:49
@kozlek
kozlek changed the base branch from devs/kozlek/devs/kozlek/batch-status-data-type/accept-namespaced-documented-data-type-marker--203218c9 to main August 5, 2026 13:52
@kozlek
kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/document-batch-status-data-type--c5cd0801 branch from 4c75840 to f86e05f Compare August 5, 2026 13:52
@kozlek
kozlek changed the base branch from main to devs/kozlek/devs/kozlek/batch-status-data-type/switch-namespaced-documented-data-type-marker--1575ebfd August 5, 2026 13:52
@mergify

mergify Bot commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

A predecessor in this stack was just merged, but I couldn't auto-rebase this PR: there's a conflict that needs manual resolution.

Conflict in: public/api-schemas.json, public/mergify-configuration-schema.json (replayed onto 59606775).

Resolve by rebasing this branch onto the latest base and pushing.

@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 5, 2026 13:53 Failure
A batch's `status.code` appeared on the API reference as a bare list of
values with no explanation, and nowhere else in the docs. Readers seeing
a status in an API response, in the CLI, or on a dashboard chip had no
way to find out what it meant.

Add a Batch Status section to the data-types page, rendering a table
generated from the OpenAPI spec so the codes and their descriptions come
from the engine rather than being hand-maintained, and cross-reference it
from the monitoring and batches pages. The table goes through the shared
reader added earlier, so it already handles the shapes a synced schema
can arrive in — a `$ref` to a hoisted component in particular, which the
engine's enum deduplication produces.

Extend the anchor build gate to scan the API spec alongside the
configuration schema. This is the first data type marked in the API
spec, and schema syncs land as direct pushes to main, so the deploy
build is the only gate they pass through.

The bundled schemas are what the sync bot will deliver once the engine
side merges. They carry the per-value documentation as `x-mergify-enum`,
a positional array aligned with `enum` holding a description, an optional
display title and a deprecation flag, and the data-type marker under its
namespaced spelling. `x-enum-descriptions` is gone: that name is an
established openapi-generator convention for a positional array of
strings, and publishing a map under it would mislead the SDK generators
customers run against our spec.

Part of MRGFY-8330

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Change-Id: Ic5cd08016af10408a80c0d9f72b86dd61abc0a84
@kozlek
kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/switch-namespaced-documented-data-type-marker--1575ebfd branch from 48a347c to a05bc6a Compare August 5, 2026 14:01
@kozlek
kozlek force-pushed the devs/kozlek/devs/kozlek/batch-status-data-type/document-batch-status-data-type--c5cd0801 branch from f86e05f to 62175a1 Compare August 5, 2026 14:01
@mergify
mergify Bot had a problem deploying to Mergify Merge Protections August 5, 2026 14:02 Failure
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants